Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / PPT100.ZIP;1 / PPT.DOC < prev next >

Wrap

Text File | 1993-05-01 | 48.0 KB | 1,014 lines

GL Software Services PPT.DOC Version 1.0 -- April, 1993 Copyright (c) 1993, Gary L. Levine, All Rights Reserved 4255 South Buckley Road #295, Aurora CO, 80013 303.840.2840 (BBS) CompuServe: 70152,253 Internet: 70152.253@compuserve.com D O C U M E N T A T I O N ========================= Table of Contents ----------------- Introduction............................................ 1 Quick Start / Tutorial.................................. 3 Acknowledgements........................................ 3 Registration............................................ 4 Support and Feedback.................................... 4 System Requirements..................................... 5 Disclaimer.............................................. 5 Tutorial................................................ 6 Configuration....................................... 6 Text / C Identifier Search.......................... 8 Drives Usage........................................ 11 Search and Replace Identifier....................... 12 Function Flow Analyzer.............................. 14 Set Files Date / Time............................... 19 Misc Features........................................... 20 Startup Options..................................... 20 @ Files............................................. 20 Hotkeys............................................. 21 Help System......................................... 21 Troubleshooting......................................... 22 Limitations......................................... 22 Resetting the database.............................. 22 PPT Version 1.0 - File PPT.DOC Page 1 ------------------------------------------------------------------ Introduction ------------ PPT is a program I developed for my own use as a professionally employed programmer. Some of the capabilities of PPT are available in commercial products, but not all together, and at a considerable price. Other features I have not found available anywhere, which is why I decided to write them myself. PPT is a set of utilities to make programmers more productive. Although PPT will be useful to all programmers, it will be especially useful to C programmers. It includes tools to analyze the structure of C programs, quickly find (and rename if desired) identifier references, document function calls in your code, and many other features. It is divided into several modules: 1) Text / C Identifier Search - A very enhanced grep-like utility with the following features: Searches for pure text or C identifiers. Searches for multiple text/identifiers and multiple source modules in a single pass. Case sensitive or insensitive searches. Automatically searches included header files ... very useful for quickly locating and displaying macro definitions. Scrollable output display with search items highlighted, and direct links to your own editor and viewer programs. Ability to save, recall, and rerun previous searches. Reports to printer or file. 2) C Identifier Search and Replace - A utility to replace (rename) a C identifier with another, with the following features: The same intuitive interface as the Text/C Identifier Search module. Works on multiple modules. Automatically creates backup files. PPT Version 1.0 - File PPT.DOC Page 2 ------------------------------------------------------------------ 3) Function Analyzer - A utility to analyze the function call hierarchy of multiple C source modules, with the following features: A scrollable visual display of the function call tree, with direct links to your own editor and viewer programs. Split-screen views of (1) All functions in all modules, (2) All functions which call the function being examined, and (3) All functions not directly called by another. Ability to exclude particular functions from the analysis by listing them in an exclusions file. Quick search capability to find a particular function in the call tree. Ability to "collapse" the path to a particular function call, showing the direct sequence of calls which lead to it. Ability to update your source files with comment headers for each function showing what other functions call it. Ability to save, recall, and rerun previous analyses. Reports to printer or file, with numerous options. 4) Drives / Files Usage - A utility to display drive usage for multiple logical drives, with the following features: Can display up to 15 logical drives per scenario, and you can store up to 5 scenarios. Numeric and graphic displays. Number of files display. 5) Set Files Date/Time - A utility to set the date and time stamp for multiple files at once. 6) In addition to the specific modules, the following general features are incorporated: Context sensitive help available everywhere by pressing F1. Command line options to allow a quick jump to a particular module. Shell to DOS feature with maximum memory available at the DOS prompt. Numerous hotkeys for quick jump to main menu, quick exit to DOS, switch between function analyzer and search module, and more. Press Alt-H for a pop-up list. "Sticky fields". PPT always remembers the settings and where you were in a display the last time you ran a particular module. Continuous progress displays for searches and analyses. Runs well under DESQview, Windows, and OS/2. PPT Version 1.0 - File PPT.DOC Page 3 ------------------------------------------------------------------ Quick Start ----------- If you are the type (as many of us programmers are) who hate to read manuals, and prefer to explore the software on your own, here's what you need to know to do that. Start the program by typing PPT. After the welcome screen delay you will be presented with the main menu. I suggest you start with "Configure System", and walk through each of the 3 choices on that sub-menu. Use the on-line Help (F1) for an explanation of each screen. Once you've configured, escape back to the main menu and have at it. You might also want to browse through the help index. Also try Alt-H for an explanation of the hot keys. Tutorial -------- I think the best way to show what PPT does and how you can use it to become a more productive programmer, is through the use of a tutorial. Please take a few minutes and walk through it. Keep in mind that context-sensitive online help is always available by pressing F1. Acknowledgements ---------------- My thanks and gratitude to my fellow programmers at MIS, Inc. for their enthusiastic reception of PPT, their thoughtful suggestions, and their uncanny ability to crash it. Mr. Barry Nance kindly gave permission to use the source code from his LIST file browser for the tutorial. His program is described in the February/1993 issue of Byte Magazine, page 235. You are free to use, customize, distribute this source code as you wish, provided you do not charge any money for it, and provided you leave the copyright notice intact. None of the registration fee for PPT pertains to LIST.C. Without the love, patience, and encouragement I received from my wife Karen, this project would never have gotten out the door. PPT Version 1.0 - File PPT.DOC Page 4 ------------------------------------------------------------------ Registration ------------ PPT is distributed as shareware. You are encouraged to share copies of PPT with friends and associates, and to upload it to bulletin boards. When distributing PPT, you MUST distribute only the archived file PPT100.ZIP, to insure that all necessary files are included. If you decide to keep and use PPT you must pay the appropriate registration fee. Please fill out the form in REGISTER.FRM to register. The form can be printed from inside PPT if you wish. Select "Register!" from the main menu. Registration buys you support (via CompuServe or our BBS), notification of future upgrades, and the warm feeling you get from knowing you are supporting the shareware concept! You only pay for this software ONCE (what a concept!). Any and all future upgrades are NO CHARGE once you're registered! This evaluation version is complete and identical to the registered version with the exception that you cannot bypass the initial welcome screen or the registration screen that appears on exit, and you cannot save scenarios. Support and Feedback -------------------- Technical support is provided for registered users via CompuServe mail. My user name and address are: Gary L. Levine 70152,253. I check my mail daily and will respond promptly to all queries. Additionally, I run a small BBS for support of PPT. The BBS phone number is 303.840.2840. The BBS software is Maximus 2.0 for OS/2. Protocol is N81 (no parity, 8 data bits, 1 stop bit), and you are dialing into a Hayes Ultra96 modem. You may leave mail, and you will always be able to find the latest version of PPT, along with notices of upcoming upgrades, etc. Support is also available by mail of course. PPT is a program intended to make programmers more productive. I have used it almost daily for the last year and a half. Many of its features were inspired by the other programmers I work with. I have a long list of enhancements planned for PPT. I would love to hear your comments, suggestions, and (ouch!) criticisms. Based of course on the response that PPT generates, I hope to continually improve and expand on it. Let me know what you think! PPT Version 1.0 - File PPT.DOC Page 5 ------------------------------------------------------------------ System Requirements ------------------- PPT requires an IBM compatible PC with an 80286 processor or better. Since PPT is a collection of utilities for programmers writing code, this minimal platform should not be a problem. It would be hard to imagine anyone doing development work these days on anything less powerful than this. It has been tested with DOS 5.0, but should work all the way back to DOS 3.x. It will run in a Windows DOS box (tested with 3.1), and a Virtual DOS Machine under OS/2 2.0. Icons for Windows and OS/2 are provided. Your CONFIG.SYS FILES setting should be at least 30. Disclaimer ---------- Use this program at your own risk. There are no warranties either express or implied. The author will not be liable for any damages relating to the use of this product. PPT Version 1.0 - File PPT.DOC Page 6 ------------------------------------------------------------------ Tutorial -------- Configuration ------------- First, start the program by typing PPT. If you are running the non-registered evaluation version, you will first see an identification screen. Press any key to continue to the main menu. The first thing you should do with PPT is configure it for your particular working environment. From the main menu, select "Configure System". We will walk through each of the items on the configuration submenu separately. Select "General" first. General - The first item is "Swap to EMS". PPT has a shell to DOS feature. When you shell out, PPT is swapped out of memory so that you will have the maximum amount of memory to work with while shelled. Enter "Y" here if you want the system to swap to expanded memory (when available). The "Alt Swap Path" indicates where PPT will be swapped if you enter "N" to the previous field, or if not enough expanded memory is available. You may enter multiple paths here. The syntax is the same as the DOS PATH environment variable. Enter "Y" to "Bypass Welcome" if you wish to bypass the welcome screen when PPT starts up. This feature is only active if you have registered the program. "Shell Prompt" allows you to set the command prompt which will be in effect when you shell to DOS. Same syntax as the DOS PROMPT command. You may use an "@" file if you have a long prompt that won't fit in the provided space. If you need to back up and reenter a field, press Shift-Tab. If you want to escape from the input screen without processing, press ESC. After you have entered all items, you will get a confirmation prompt at the bottom of the screen. Enter "Y" if you are satisfied with your input. Enter "N" to reenter. You may press F10 (the accept or GO key) at any time to immediately process all screen data. This is a standard feature on all input screens. After you have finished this screen, select "Editors / Viewers" from the configuration menu. PPT Version 1.0 - File PPT.DOC Page 7 ------------------------------------------------------------------ Editors / Viewers - One of PPT most powerful features is the ability to jump directly from one of PPT' analyses to the corresponding line in your source code, using your favorite editor or viewer programs. This input screen is where you set up the link to those programs. There are 2 fields for each program. The first is the name of the program, which will show up next to the appropriate function key on the output screen for each module. The 1st editor/viewer program is invoked in each module by pressing the ENTER or F3 key. The 2nd editor/viewer program is invoked by pressing the F4 key. One approach to these fields would be to set up one to use a simple viewer or browser program which would load very quickly for one of the programs, and a full-fledged editor for the other. The "Command to invoke" field is where you enter the command which will start your editor/viewer program with the appropriate file and at the desired line number. In this field, enter a "%s" where the file name should go, and enter "%ld" where the line number should go. For examples, we have used Vern Buerg's famous LIST program as the default for editor/viewer 1, and the BRIEF editor as the default for editor/viewer 2. Press the HELP key (F1) to see some examples for other programs. Be sure and enter a fully qualified path if your program is not in your DOS PATH environment variable. Next, select "Drives" from the configuration menu. The "Drives Usage" module of PPT allows you to see at a glance the available drive space for a number of logical drives at once. Up to 15 logical drives can be specified for each of 5 different scenarios. One typical use would be to set up one scenario to display your local drives, and another to display network drives. For each scenario, enter the drive letters you want displayed. You may put spaces between the letters, but it is not necessary. The last field, "Default Display", will present a pop-up window and allow you to select either "Numeric" or "Graphic" as the default display mode. The "Drives Usage" module allows you to toggle easily between the two. This field merely indicates which mode will be active when you first enter the module. That's it! You're all set to begin your test drive. Let's start with the search module. PPT Version 1.0 - File PPT.DOC Page 8 ------------------------------------------------------------------ Text / C Identifier Search -------------------------- This module allows you to search across a number of source modules for a specific C identifier or text string. For this illustration, we will be using the the three sample C source files: LIST1.C, LIST2.C, LIST.H. Choose Text / C Identifier Search from the main menu. The first field on the input screen is where you enter the actual identifier or text you will want to search for. You may enter up to ten different identifiers/strings to search for at once. If more than one is entered they should be space delimited. You cannot search for identifiers and text in the same pass. Text items with embedded blanks should be enclosed within double quotes. Wildcards are supported for text searches. "@" files are supported. If you want to search for a C structure element, enter it as "structure.element", which will report all occurrences of both "structure.element" and "structure->element". Note: Try F1-Help while in this input screen. It explains all input fields in detail. For our illustration enter the following for Text/Identifier: ESC fgetbyte icase noaccess For Search Files, enter: LIST*.C LIST.H For Text Or Identifier Search you are presented a pop-up screen. The cursor should be highlighting "Identifier Search". Press return to accept this. For Case Sensitive, enter "Y". For Scan Include Files, enter "N". If you enter "Y", PPT will search all included header files automatically. However, unless you have a Borland C compiler installed, you will likely get a warning message that PPT cannot find one of the included .H files. For this tutorial, you can just ignore that message. Scanning include files is a very powerful feature which allows you to determine very quickly where and how a particular macro is defined. Press enter at the confirmation message to start the search. A progress window will appear while the search is progressing. When the search is done the output display will appear. PPT Version 1.0 - File PPT.DOC Page 9 ------------------------------------------------------------------ The output display has the date and time of the search in the upper left hand corner. The display itself is a scrollable listing of all occurrences of your search identifiers, organized by module. Actual occurrences of each identifier are shown in yellow for easy visual identification. You can scroll through the display using the normal cursor keys. Press END to get to the bottom of the display. You will see a summary of the number of files and lines scanned, and the number of occurrences found of each search identifier. Scroll up and down using the arrow keys. Notice that when the cursor bar is on an actual line of code, the name of the source module appears in the upper right hand corner of the display. The "ENTER/F3" key on the bottom legend should be displaying the name of your first editor/viewer program that you configured earlier. The "F4" key should be displaying the name of your second editor/ viewer program. These keys allow a direct link to your source code, and are one of the most powerful features of PPT. Move the cursor bar to the first source line under LIST2.C, the line that reads: 39 extern char *noaccess; Now press ENTER or F3. If you have configured your editor/viewer programs properly, your first editor/viewer program should come up, with LIST2.C loaded, and placed on line 39. (If your program does not support positioning on a specific line, you may be at the top of the module instead.) Work inside this program as you normally would. When you exit from the editor/viewer, you will be back in PPT. Try pressing F4. The same thing should happen with your second editor/viewer program as happened when you pressed ENTER or F3. If you have any problems with this, review the configuration section of this documentation. Let's suppose you want to produce a printed report from this search, but that you're not interested in the prototypes that showed up in the output. Position the cursor on the following line in LIST.H: 96 void search_setup(unsigned char *pat, int plen, int icase); Press the DEL key to hide this line. Notice in the lower right hand corner, an "HR" icon has appeared, indicating that there are "hidden records". To restore this record, press INS. The "HR" icon will disappear. If you have hidden several records, INS will restore them one at a time. To restore them all at once, press CTRL-I. PPT Version 1.0 - File PPT.DOC Page 10 ------------------------------------------------------------------ To produce a printed report of this search, press F2. The input screen is fairly self explanatory. Enter up to 4 lines of title. For Output File or Printer Device, enter a valid printer port, or a file name to send output to. If necessary, change the default values for Lines Per Page and Left Margin. Press F10 to start the report, or press enter until you get to the confirmation message. Now, press ESC to get back to the input screen. From here, pressing F9 will return you to the output display, but for the moment, stay here. NOTE: THE FOLLOWING DISCUSSES SAVED SCENARIOS WHICH ARE ONLY ACTIVE IN THE REGISTERED VERSION. Notice the F2 and F3 keys for loading and saving scenarios. Each time you execute a search, it overwrites the previous scenario, UNLESS you have SAVED the previous scenario. To save a search scenario, press F3. Press F3 now. Now, press F2. What you see is a screen showing the scenarios you have saved. You press enter to load a saved scenario, or DEL to remove one. You can store as many scenarios as you want, limited only by available disk space. As a practical matter however, you will want to remove scenarios you no longer need, since doing so will improve performance. Try some more searches on your own. Try some text searches as well as identifier searches. Try setting the Case Sensitive field to "N". Try saving and loading multiple scenarios. Press F1 for help, go to the Help Index, and read about "@ Files". Try using one for the Search Files field. Try starting a search and pressing ESC while it's still in progress. Notice how you can stop immediately, and still not lose the results of your search up to that point. Exit from PPT using ALT-X (quick exit). Now start it up again using the command "PPT SV" which will take you directly to the search viewer. Notice that the cursor is still on the line it was when you exited! Most fields in PPT are "sticky" in this way. They remember where you were when you left, and what your input choices were the last time you used each module. PPT Version 1.0 - File PPT.DOC Page 11 ------------------------------------------------------------------ Drives Usage ------------ Select Drives/File Usage from the main menu. You will see a usage display for the logical drives you entered for scenario 1 when you configured the system. If you selected "graphic" for the default display, the amount of disk space used will appear as a subdued green bar, and the amount free will appear as a bright green bar. You will also see the amount free as a numeric value, and as a percent of total space available. Totals for all drives appear at the bottom. If you selected "numeric" for the default display, the graphic bar will be replaced by numeric fields, as well as an indication of the drives volume label. Toggle the F2 key to see the difference between the numeric and graphic display. Try toggling through your scenarios by pressing F5 repeatedly. This procedure will have no effect unless you set up more than one scenario. Press F3 to display the number of files on each logical drive. This can take a bit of time on a drive with a very large number of files. You can press ESC at any time to interrupt the count. PPT Version 1.0 - File PPT.DOC Page 12 ------------------------------------------------------------------ Search and Replace Identifier ----------------------------- This module allows you to replace the occurrence of a particular C identifier (variable, function name, macro, etc.) with another, across multiple source modules. The interface is very similar to the Text / C Identifier Search module. You should be sure and walk through that example before this one. For this illustration, we will be using the sample files LIST1.C and LIST2.C. We are going to replace all instances of the variable "i" with "I" (upper case). Choose Search and Replace from the main menu. For Old Identifier, enter "i" (without the quotes). For New Identifier, enter "I". For Modules To Update, enter LIST*.C. For Update Include Files, enter "N". For Backup Files Extension, you can accept the default BAK, or enter another extension up to 3 characters long. PPT makes automatic backups of your files before changing them. Even so, if you are the overly-cautious type (like I am!), you may want to make copies of your source files yourself, even though PPT will also. After the modules are searched, you will see a scrollable display virtually identical to the one in the Text / C Identifier Search module. Occurrences of "i" will be highlighted. Function keys F2, F3/ENTER, and F4 operate as they do in the in the previous search module. F5 starts the update process. Press F5 now. You will see several progress displays during the update. When it is finished, a message window regarding backup files will be displayed. Press enter, and you will be returned to the input screen. Now let's look at the changed files. This is a good time to try a couple of the hotkeys. ALT-F3 and ALT-F4 are active everywhere in the system, and allow you to bring up either of your editor/ viewer programs, with a file which you specify through an input window. PPT Version 1.0 - File PPT.DOC Page 13 ------------------------------------------------------------------ Press ALT-F3 now. Enter the file name LIST2.C and press enter. You will be placed in your first editor/viewer program with LIST2.C loaded. Scroll around and satisfy yourself that all occurrences of "i" are now "I". When you exit your editor/viewer, you will be back in PPT. Now let's see if the backup files actually got created. Press ALT-D to shell out to DOS. Type the command DIR *.BAK (or whatever extension you selected for the backup files). You should see entries for LIST1.BAK, and LIST2.BAK. Notice while you're shelled out to DOS that your prompt has changed to whatever you set it up to be during configuration. Just type EXIT to get back to PPT. That's all there is to it. Imagine the benefit of replacing a variable name in 10 or 20 modules (or more!), instead of having to do it file by file with your editor. PPT Version 1.0 - File PPT.DOC Page 14 ------------------------------------------------------------------ Function Analyzer ----------------- This module allows you to interactively peruse the function hierarchy (i.e., call structure) of a program. I have found it extremely useful for analyzing someone else's source code, as well as my own code that I haven't looked at for a while. For purposes of the tutorial, we will again be using the LIST1.C and LIST2.C modules. Choose Function Analyzer from the main menu. For Source Modules, enter LIST*.C. The Exclude Files field allows you to enter the name of a text file which has a list of functions you want to exclude from the analysis. A typical use would be to exclude functions from the run-time library, so you can focus on application calls only. A template file for this purpose is included and named RTLIB.EXC. You may want to browse through it and edit it for your own purposes. For now, leave this field blank. The Start Function field allows you to specify which function to start the hierarchy analysis with. For now, accept the default of "main", so we can examine the entire call structure. If at some point you are trying to analyze an extremely large project and run out of memory, you can enter a lower-level function instead of "main", which will require less memory to analyze. The Function Headers field will display a pop-up screen with the following choices: 1 - Do Not Generate 2 - Generate with /* */ 3 - Generate with // 4 - Remove Function headers are comments that are generated automatically and placed in your source code just prior to each function declaration. The comment indicates what other functions call the one documented. Choice (1) will not generate any comment headers. Choice (2) will generate them with traditional C comment delimiters (/* */). Choice (3) will generate them with single line comment delimiters (//), and Choice (4) will remove headers already in your code. For now, accept the default of Do Not Generate. The next field, Backup Files Ext. will be deactivated. Backup files are only generated if you choose an option that modifies your source code. PPT Version 1.0 - File PPT.DOC Page 15 ------------------------------------------------------------------ In the call tree display, lower level functions are indented to show the hierarchy. You can control the amount of indentation with the field Spaces To Indent Each Level In Call Tree. The call tree display can optionally include the nesting level (where main is level 1, functions called by main are level 2, etc). For now, leave the field Show Nesting Level In Call Tree as "N". Show Duplicate Function Calls controls whether each and every call of a function by another is shown in the call tree, or just the first occurrence is shown. Suppose you have a function called printem() which calls printf() 5 times. With Show Duplicate Function Calls set to "N", only the first occurrence will be shown. If you set it to "Y", all occurrences will be shown. Setting this field to "Y" may require significantly more time and memory for the analysis. For now, leave it set to "N". After you accept the confirmation message, the analysis will begin. When it's finished, you will be placed in a scrollable display of the call hierarchy. The cursor will be on "main" at the top of the display. Scroll through display using the arrow keys and note the source file name which appears (and changes) in the upper right corner. This indicates which source file the highlighted call appears in. The number in the left hand column is the line number in the source file where the actual call appears. The ENTR/F3 and F4 keys work as they do in the search modules to link you directly to your source code. Cursor down to the call to get_video_mode and press ENTR or F4. You should be in your editor/ viewer program with LIST2.C loaded, and positioned at line 601, which is where the actual call to get_video_mode occurs. Exit out of your editor/viewer program back to the PPT display. Let's try out a few of the other function keys. Press F6. This brings up a display of all functions encountered during the analysis, with the cursor on the same function that is highlighted in the call tree, in this case, get_video_mode. Press ENTR/F3 or F4 here and you will link to your source code where get_video_mode is actually defined (as opposed to where it was called). Now go back to PPT. You can jump quickly to a function in this function list by simply typing in the function name. As you type, the cursor will zero-in on the appropriate name. Try typing "showfile" to see how this works. Let's look at the other 2 split screens that are available. You can exit this split screen by pressing ESC, a left or right arrow, or another function key. Press ESC to clear the split screen. PPT Version 1.0 - File PPT.DOC Page 16 ------------------------------------------------------------------ Place the cursor on one of the calls to "lseek". Now press F8. This split screen displays all the functions which call lseek. Place the cursor on "find_text" and press ENTR/F3 or F4. You will be in LIST1.C at line 603, where lseek is called by find_text. Now, press F10. This final split screen shows all functions which are not directly called anywhere in the program. That is, they are either not called at all, or they are called indirectly through a pointer. "main" will always appear in this list, since it is called by the operating system and not the program. In our example, there are no other functions that are not directly called. Press ESC to exit the split screen display. The F5, F7, and F9 function keys are used to quicly locate a function call in the hierarchy. Press F7. A pop-up window appears where you can type in a function name. Type in "fgetbyte" and press enter. The cursor will jump forward to the first occurrence of that function call. Press F5 to search backward, and F9 to search forward. There is a second legend with more key functionality. Press Ctrl-M to toggle the legend. You can hide records in the hierarchy display in the same way you do in the search modules. The difference is that pressing DEL will hide the highlighted function, and ALL FUNCTIONS CALLED BY IT. To see how this works, first press HOME to the position the cursor at the top of the display. Now cursor down to the first call to save_cursor, and press DEL. Notice how the call to geninterrupt also disappears. To restore hidden lines one at a time, press INS. To restore them all at once, press Ctrl-I. This module provides the unique capability of showing the direct call path to a particular function. Press PageDown a few times to position the cursor on the "read" call at line 262 in LIST2.C. Now press Ctrl-P. The path to the highlighted call is immediately "collapsed" so you can see the direct route to this call from main. You can restore the display by pressing Ctrl-I. PPT Version 1.0 - File PPT.DOC Page 17 ------------------------------------------------------------------ Now press Ctrl-M to toggle back to the main legend. The last function key to look at is F2 which generates a printed report. Press F2 now. A pop-up appears permitting you to select a combination of 3 reports: (1) The Call Tree Report (a printed version of the hierarchy display), (2) The Called-By Report (a printed version of F8), and (3) The Not-Called Report (a printed version of F10). Enter "Y" for all 3 reports. If you have a printer capable of printing the same line drawing characters which appear in the call tree display, enter "Y" to Print Line Chars. If you have an HP Laserjet printer or compatible, answer "Y" to Download HP Font, and a special soft font will be automatically downloaded which contains the appropriate line drawing characters. You are now presented with the same report generation input screen that we saw in the search module tutorial. Fill it out as appropriate. When the report is finished, you will be back at the call tree display. Let's look at a couple of features that we skipped over in this first example. Press ESC to return to the Function Analyzer Input screen. Let's run the same analysis with the following changes: For Exclude Files, enter "LIST.EXC". For Func Headers, enter "2 - Generate with /* */". For Show Nesting Level In Call Tree, enter "Y". Press F10 when ready. You'll notice some additional progress messages relating to updating your source files with comment headers, and the creation of backup files. When you get to the call display, you will notice a couple of differences. First, each function name is preceded by a number indicating the nesting level of the call. This can be very useful in long, deeply nested programs. Also, if you scroll through the display, you'll notice that it's much shorter than our previous example, and that some functions seem to be "missing". This is because we excluded from the analysis the files listed in the file LIST.EXC. Sometimes eliminating low-level run-time library functions can give you a quicker overall feel for the structure of the program. Now, press F6 to get a list of all functions analyzed. Cursor down to the function "display_line", and press ENTR/F3 or F4. When in your editor/viewer program, look just ahead of the display_line definition to see the comment header inserted. It indicates that this function is called by showfile in LIST1.C, and by fill_window in LIST2.C. Using this auto-doc feature can significantly enhance your productivity when analyzing new source code. PPT Version 1.0 - File PPT.DOC Page 18 ------------------------------------------------------------------ Now get back to the Function Analyzer input screen. The F2 and F3 keys for saving and loading scenarios work exactly like they do in the search module. Refer to that section for a detailed explanation. PPT Version 1.0 - File PPT.DOC Page 19 ------------------------------------------------------------------ Set Files Date / Time --------------------- This module allows you to set the date and time stamp to any values you choose, and works on multiple files. Choose Set Files Date/Time from the main menu. The input form has fields for the files to modify, and the date and time to set them to. The date and time are set by default to the date and time you entered the module. The files specification can be include a relative or absolute pathname, as well as the wildcard characters '*' and '?'. Multiple groups of file specs can be entered if space delimited. "@" files are supported. Try entering "LIST*.*" which will modify the 3 C source files that are included as sample files for the tutorial. Enter a date in the format "mm/dd/yy", but don't enter the slashes, they are pre-entered. Enter a time in the format "hh:mm:ss". Use military time (24 hour clock) for hours after 12:00 noon. You must enter the ":" character. Seconds are optional. Press return in response to the confirmation message to actually perform the update. You will see a result window which will indicate the number of files actually modified. PPT Version 1.0 - File PPT.DOC Page 20 ------------------------------------------------------------------ Miscellaneous Features ---------------------- Startup Options --------------- The program is started by typing PPT at the command line. You can rename this program, but you CANNOT rename any of the other .EXE files which are called by PPT.EXE. PPT supports a number of command line options for quickly jumping to a particular module: PPT C Go directly to the Configuration menu. PPT D Go directly to the Drives Usage module. PPT F Go directly to the Function Analyzer input screen. PPT FV Go directly to the Function Analyzer output viewer. PPT L Go directly to the Set Files Date/Time module. PPT R Go directly to the Search and Replace input screen. PPT RV Go directly to the Search and Replace output viewer. PPT S Go directly to the Text / C Ident Search input screen. PPT SV Go directly to the Text / C Ident Search output viewer. The command line options are NOT case sensitive. @ Files ------- A number of the input fields in various modules support "@" files. Where this support is indicated (use F1-Help from the input screen), the user may put a list of the requested items in a text file and enter the name of the text file (with a path component if necessary) prefixed with an "@" for the input field. The "@" file should have one item per line. For file specifications, wildcard characters "*" and "?" are supported. Blank lines and lines that begin with a ";" are ignored. For example, the Function Analyzer module has an input field for the source files to be analyzed. Rather than list all the files individually in this field, the user could enter "@ACCTG.FLS, where the file ACCTG.FLS looks as follows: ACCTG.FLS --------- ; Source files for the Accounting Project C:\ACCTG\*.C C:\ACCTG\*.H C:\ACCTG\LIB\*.C PPT Version 1.0 - File PPT.DOC Page 21 ------------------------------------------------------------------ Hotkeys ------- PPT supports a number of hotkeys: Alt-A Dedication and acknowledgments. Alt-D Shell out to DOS. Alt-F Jump to Function Analyzer viewer. Alt-F3 View a file with F3 editor/viewer (1). Alt-F4 View a file with F4 editor/viewer (2). Alt-H Display the hotkey help pop-up. Alt-M Jump to main menu. Alt-R Jump to Search and Replace viewer. Alt-S Jump to Text / C Ident Search Viewer. Alt-T Display date and time. Alt-X Quick exit to DOS. Help System ----------- Context-sensitive help is available everywhere in the system by pressing F1. Each help screen has additional choices at the bottom of the screen, allowing you to jump to the help topic index, page forward and backward, and exit the help system. There may also be choices for help on related topics. You can cycle through these choices with the cursor keys. You can also select them by pressing the appropriate (highlighted) hotkey. Pressing ESC in a help screen will back you up to the previous screen. Pressing F10 will immediately exit the help system. PPT Version 1.0 - File PPT.DOC Page 22 ------------------------------------------------------------------ Troubleshooting --------------- Limitations ----------- Drives Usage ------------ The SIZE and USED fields cannot accurately report an amount of disk space larger than 268 megabytes. Function Analyzer ----------------- The function analyzer requires syntactically correct C code. If your code does not compile cleanly, PPT can hang. The function analyzer does not currently recognize "#if"-type statements. If you get an unbalanced braces or parentheses message (although your code compiles without errors), look for a brace or parenthesis imbalance within your "#if" directive. Maximum number of modules you can analyze is 150. Maximum number of function references is 5000. Function names cannot be greater than 30 characters. You can specify no more than 10 exclude files. There can be no more than 1350 exclude functions. The maximum length of a C source line is 1024 bytes. The function analyzer's real-world limitations are directly dependent on the amount of available conventional memory. If you get a message indicating there is not enough memory to complete the analysis, try increasing your available memory. You should also answer "No" to "Show Duplicate Function Calls" on the input screen. You could also try "excluding" more functions. You can also subdivide your analysis into a number of smaller analyses with lesser scope. Resetting the Database ---------------------- It's possible under certain conditions for the database in PPT to become corrupted. To reset it, run the program RESETDB.EXE. If you run it without any command line parameters, it will reset your database, but leave your configuration choices intact. If you run it with a "-d" command line parameter, the original distribution default configuration will be restored.